<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
<head>
	<meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
	<meta name="description" content="description"/>
	<meta name="keywords" content="keywords"/>
  <meta name="author" content="Kyle Yetter"/>
	<link rel="stylesheet" type="text/css" href="stylesheets/article.css" media="screen"/>
  <link rel="stylesheet" type="text/css" href="stylesheets/generic.css" media="screen"/>
  <link rel="stylesheet" type="text/css" href="stylesheets/ANTLR3.css" media="screen"/>

	<title>ANTLR For Ruby: Getting Started</title>
</head>

<body>
<div class="left">
	<div class="header">
		<h2><span>ANTLR for Ruby</span></h2>
		<h1>Getting Started</h1>
	</div>
	<div class="annotation">
		<div class="author">by <a href="mailto:kcy5b@yahoo.com">Kyle Yetter</a></div>
    <div class="timestamp">updated Sunday, August 04, 2013 at 09:59PM EDT</div>
	</div>
	<div class="content">
<h1 id="section-1">Installing</h1>
<h2>Rubygems</h2>
<p>The simplest way to install the <code>antlr3</code> ruby project is via <a href="http://www.rubygems.org">rubygems</a>.</p>
<div class="naked-code-frame">
  <div class="code-header">Installing Via Rubygems</div>
  <table class="generic" id="70001867554460">
  <tr class="code_line" id="70001867554460-1">
    <td class="code"><pre><span class="gp">~&gt;</span><span class="w">&nbsp;</span><span class="ni">gem</span><span class="w">&nbsp;</span><span class="nv">install</span><span class="w">&nbsp;</span><span class="nv">antlr3</span></pre></td>
  </tr>
</table>

</div>
<h2>Source Archive</h2>
<p>There are source zip-file distributions of the source code available for download at <a href="http://rubyforge.org/frs/?group_id=8857&amp;release_id=42688">Rubyforge</a>. However, be aware that the zip distribution does not include any setup/installation script currently and the <code>antlr4ruby</code> tool must be able to locate the file java/antlr-full-3.&#215;.&#215;.jar in the project&#8217;s base directory. <!-- TODO: explain this better --></p>
<h2>GitHub</h2>
<p>The full source code and development history can be cloned from my <a href="http://github.com/ohboyohboyohboy/antlr3">GitHub repository</a>. Note that the repository code is much larger and full of dependencies than the source packages listed above. If you are primarily interested in simply using this package to generate recognition code, you are probably better off installing the gem or source package as described above. The gem and zip package distributions contain everything needed to use the ruby target without any external dependencies.</p>
<h1 id="section-2">Running <span class="caps">ANTLR</span></h1>
<p>Included in the package is the program <code>antlr4ruby</code>, which is a thin wrapper around the <span class="caps">ANTLR</span> tool command. Thus, it is invoked exactly like the <span class="caps">ANTLR</span> tool. Refer to <a href="http://www.antlr.org/wiki/display/ANTLR3/Command+line+options">this list of <span class="caps">ANTLR</span> tool command-line options</a> for more information. So, to generate recognition code for input grammar <code>Whatevs.g</code>,</p>
<div class="naked-code-frame">
  <div class="code-header">Generating Ruby Code From a Sample <span class="caps">ANTLR</span> Grammar, <code>Whatevs.g</code></div>
  <table class="generic" id="70001867792460">
  <tr class="code_line" id="70001867792460-1">
    <td class="code"><pre><span class="gp">~&gt;</span><span class="w">&nbsp;</span><span class="ni">antlr4ruby</span><span class="w">&nbsp;</span><span class="nv">Whatevs.g</span></pre></td>
  </tr>
</table>

</div>
<h1 id="section-3">Grammar File Options</h1>
<p>To generate ruby code, you must specify a top-level option block that sets <code>language = Ruby;</code></p>
<div class="code-frame">
  <div class="code-header">Ruby-Targetted Grammars Require <code>language</code> Option</div>
  <table class="ANTLR3" id="AnyRubyGrammarYouWrite">
  <tr class="code_line" id="AnyRubyGrammarYouWrite-1">
    <td class="line_number odd"><pre>01</pre></td>
    <td class="code"><pre><span class="k">grammar</span><span class="ws">&nbsp;</span><span class="name">AnyRubyGrammarYouWrite</span><span class="p">;</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AnyRubyGrammarYouWrite-2">
    <td class="line_number even"><pre>02</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AnyRubyGrammarYouWrite-3">
    <td class="line_number odd"><pre>03</pre></td>
    <td class="code"><pre><span class="k">options&nbsp;{</span><span class="ws">&nbsp;</span><span class="id">language</span><span class="ws">&nbsp;</span><span class="o">=</span><span class="ws">&nbsp;</span><span class="id">Ruby</span><span class="p">;</span><span class="ws">&nbsp;</span><span class="k">}</span><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AnyRubyGrammarYouWrite-4">
    <td class="line_number even"><pre>04</pre></td>
    <td class="code"><pre><span class="ws"></span></pre></td>
  </tr>
  <tr class="code_line" id="AnyRubyGrammarYouWrite-5">
    <td class="line_number odd"><pre>05</pre></td>
    <td class="code"><pre></pre></td>
  </tr>
</table>

</div>
<p>If you do not set this option, <span class="caps">ANTLR</span> assumes <code>language = Java;</code>. You will generate Java source code.</p>
<h1 id="section-4">Quickly Testing <span class="caps">ANTLR</span> Output</h1>
<p>Every recognizer file generated by <span class="caps">ANTLR</span> has a built-in recognizer script that can be used to quickly try out the recognizer. The test script code is only executed when the file is run directly, not when it is loaded by other ruby files. For example, say you are developing a grammar for recognizing the C language, <code>C.g</code>. When the grammar&#8217;s filled out to the point where <span class="caps">ANTLR</span> can compile it without errors, run</p>
<div class="naked-code-frame">
  <table class="generic" id="70001867352080">
  <tr class="code_line" id="70001867352080-1">
    <td class="code"><pre><span class="gp">~&gt;</span><span class="w">&nbsp;</span><span class="ni">antlr4ruby</span><span class="w">&nbsp;</span><span class="ss">-fo</span><span class="w">&nbsp;</span><span class="nv">C.g</span></pre></td>
  </tr>
</table>

</div>
<p>Now, if you have some sample C code in a file named <code>sample.c</code> and you would like to test out your lexer to see how it tokenizes the output code, you do not have to build a driver by hand. Simply run:</p>
<div class="naked-code-frame">
  <div class="code-header">Built-In Test Driver: Lexer Files</div>
  <table class="generic" id="70001867362260">
  <tr class="code_line" id="70001867362260-1">
    <td class="code"><pre><span class="gp">~&gt;</span><span class="w">&nbsp;</span><span class="ni">ruby</span><span class="w">&nbsp;</span><span class="nv">CLexer.rb</span><span class="w">&nbsp;</span><span class="nv">sample.c</span><span class="kp"></span></pre></td>
  </tr>
  <tr class="code_line" id="70001867362260-2">
    <td class="code"><pre><span class="go">--&gt;&nbsp;T__23&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&quot;typedef&quot;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;@&nbsp;line&nbsp;1&nbsp;&nbsp;&nbsp;col&nbsp;0</span></pre></td>
  </tr>
  <tr class="code_line" id="70001867362260-3">
    <td class="code"><pre><span class="go">#&nbsp;&nbsp;&nbsp;WS&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&quot;&nbsp;&quot;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;@&nbsp;line&nbsp;1&nbsp;&nbsp;&nbsp;col&nbsp;7&nbsp;&nbsp;&nbsp;(hidden)</span></pre></td>
  </tr>
  <tr class="code_line" id="70001867362260-4">
    <td class="code"><pre><span class="go">--&gt;&nbsp;T__39&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&quot;unsigned&quot;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;@&nbsp;line&nbsp;1&nbsp;&nbsp;&nbsp;col&nbsp;8</span></pre></td>
  </tr>
  <tr class="code_line" id="70001867362260-5">
    <td class="code"><pre><span class="go">#&nbsp;&nbsp;&nbsp;WS&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&quot;&nbsp;&quot;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;@&nbsp;line&nbsp;1&nbsp;&nbsp;&nbsp;col&nbsp;16&nbsp;&nbsp;(hidden)</span></pre></td>
  </tr>
  <tr class="code_line" id="70001867362260-6">
    <td class="code"><pre><span class="go">--&gt;&nbsp;T__34&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&quot;int&quot;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;@&nbsp;line&nbsp;1&nbsp;&nbsp;&nbsp;col&nbsp;17</span></pre></td>
  </tr>
  <tr class="code_line" id="70001867362260-7">
    <td class="code"><pre><span class="go">#&nbsp;&nbsp;&nbsp;WS&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&quot;&nbsp;&quot;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;@&nbsp;line&nbsp;1&nbsp;&nbsp;&nbsp;col&nbsp;20&nbsp;&nbsp;(hidden)</span></pre></td>
  </tr>
  <tr class="code_line" id="70001867362260-8">
    <td class="code"><pre><span class="go">--&gt;&nbsp;IDENTIFIER&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&quot;size_t&quot;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;@&nbsp;line&nbsp;1&nbsp;&nbsp;&nbsp;col&nbsp;21</span></pre></td>
  </tr>
  <tr class="code_line" id="70001867362260-9">
    <td class="code"><pre><span class="go">--&gt;&nbsp;T__24&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&quot;;&quot;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;@&nbsp;line&nbsp;1&nbsp;&nbsp;&nbsp;col&nbsp;27</span></pre></td>
  </tr>
  <tr class="code_line" id="70001867362260-10">
    <td class="code"><pre><span class="go">#&nbsp;&nbsp;&nbsp;WS&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&quot;\n&quot;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;@&nbsp;line&nbsp;1&nbsp;&nbsp;&nbsp;col&nbsp;28&nbsp;&nbsp;(hidden)</span></pre></td>
  </tr>
  <tr class="code_line" id="70001867362260-11">
    <td class="code"><pre><span class="go">#&nbsp;&nbsp;&nbsp;LINE_COMMAND&nbsp;&nbsp;&nbsp;&nbsp;&quot;#&nbsp;325&nbsp;\&quot;stddef.h\&quot;&nbsp;3&nbsp;4\n&quot;&nbsp;@&nbsp;line&nbsp;2&nbsp;&nbsp;&nbsp;col&nbsp;0&nbsp;&nbsp;&nbsp;(hidden)</span></pre></td>
  </tr>
</table>

</div>
<p>Both parsers and tree parsers also have similar built in test drivers. You can run the file with a <tt>&#8212;help</tt> switch to get more information about arguments and available options. See section <a href="./BuiltInDrivers.html">Built-In Drivers</a> for more information on using the built in quick test script feature.</p>
	</div>
</div>

<div class="nav">
	<div class="logo"><span></span></div>

	<ul>
		<li><a href="#section-1">Installing</a></li>
		<li><a href="#section-2">Running <span class="caps">ANTLR</span></a></li>
		<li><a href="#section-3">Grammar File Options</a></li>
		<li><a href="#section-4">Quickly Testing <span class="caps">ANTLR</span> Output</a></li>
	</ul>
</div>

<div class="right">
	<div class="round">		
		<div class="roundtl"><span></span></div>
		<div class="roundtr"><span></span></div>
		<div class="clearer"><span></span></div>
	</div>

	<div class="subnav">
		<h1>Contents</h1>
		<ul>
      <li><a href="./index.html">Home</a></li>
  		<li class="current">Getting Started</li>
      <li><a href="./Lexers.html">Lexers</a></li>
      <li><a href="./Parsers.html">Parsers</a></li>
      <li><a href="./Tokens.html">Tokens</a></li>
      <li><a href="./ActionBlocks.html">Action Blocks</a></li>
      <li><a href="./Scopes.html">Scopes</a></li>
      <li class="todo"><a href="./TreeParsers.html">Tree Parsers</a></li>
      <li class="todo"><a href="./ASTs.html">Abstract Syntax Trees</a></li>
      <li><a href="./BuiltInDrivers.html">Built-In Drivers</a></li>
      <li class="todo"><a href="./TemplateMode.html">Template Mode</a></li>
      <li class="todo"><a href="./DebugMode.html">Debug Mode</a></li>
      <li class="todo"><a href="./ProfileMode.html">Profile Mode</a></li>
      <li class="todo"><a href="./Extras.html">Extras</a></li>
		</ul>
		
    <h1>Project Links</h1>
		<ul>
      <li><a href="http://github.com/ohboyohboyohboy/antlr3">GitHub</a></li>
      <li><a href="http://rubygems.org/gems/antlr3">Ruby Gems</a></li>
      <li><a href="http://rubyforge.org/projects/antlr3">Rubyforge</a></li>
      <li><a href="http://github.com/ohboyohboyohboy/antlr3/issues">Bug Reports</a></li>
		</ul>
		
    <h1>External Links</h1>
		<ul>
      <li><a href="http://www.antlr.org">ANTLR.org</a></li>
      <li><a href="http://www.antlr.org/wiki/display/ANTLR3/ANTLR+Cheat+Sheet">ANTLR Cheat Sheet</a></li>
      <li><a href="http://www.antlr.org/wiki/display/ANTLR3/ANTLR+v3+documentation">ANTLR Documentation</a></li>
      <li><a href="http://www.antlr.org/grammar/list">Sample Grammar Exchange</a></li>
		</ul>
	</div>

	<div class="round">
		<div class="roundbl"><span></span></div>
		<div class="roundbr"><span></span></div>
		<span class="clearer"></span>
	</div>
</div>

<div class="footer">
	
  &copy; 2010 <a href="mailto:kcy5b@yahoo.com">Kyle Yetter</a>. Valid <a href="http://jigsaw.w3.org/css-validator/check/referer">CSS</a> &amp; <a href="http://validator.w3.org/check?uri=referer">XHTML</a>. <a href="http://templates.arcsin.se">Website template</a> by <a href="http://arcsin.se">Arcsin</a>

</div>
</body>

</html>